ESP32 WiFi Packet Sniffer

Professional Network Intelligence System with Display Interface

Technical Report & Documentation

Project Overview

This project implements a WiFi packet sniffer for the ESP32 platform, featuring a professional 1.3" ST7789 display interface and advanced network intelligence capabilities. The system is designed for network security professionals, researchers, and engineers who need comprehensive WiFi network analysis tools.

Key Innovation: This project combines traditional WiFi packet analysis with modern embedded display technology, providing both detailed serial output for technical analysis and intuitive visual interface for real-time monitoring.

Project Objectives

  • Capture and analyze WiFi management frames across all 2.4GHz channels
  • Provide real-time network intelligence through professional display interface
  • Implement advanced anomaly detection for security analysis
  • Enable target device tracking and behavioral analysis
  • Create a portable, professional-grade network analysis tool

System Architecture Flow Chart

ESP32 WiFi Packet Sniffer - System Flow

HARDWARE LAYER
ESP32-WROVER
WiFi + Processing
ST7789 Display
240x240 Interface
Touch Sensors
GPIO 32/33
FIRMWARE LAYER
WiFi Promiscuous Mode
  • Channel hopping (1-13)
  • Packet capture
  • Frame classification
LVGL Display Engine
  • 7 UI cards
  • Real-time updates
  • Touch navigation
PROCESSING LAYER
Packet Analysis
MAC extraction, SSID parsing, vendor identification
Anomaly Detection
Probe floods, deauth attacks, suspicious patterns
Target Tracking
MAC monitoring, signal strength, behavioral analysis
DATA LAYER
AP Database
SSID, BSSID, Security
Client Registry
MAC, Vendor, Status
Channel Stats
Activity, Utilization
Threat Log
Anomalies, Alerts
OUTPUT LAYER
Serial Interface (Primary)
  • 6 output modes (SILENT to ANALYST)
  • Classic packet format
  • Professional notifications
  • Live dashboard
Display Interface (Secondary)
  • Real-time statistics
  • Visual network overview
  • Touch navigation
  • Status indicators
System Operation Flow
1
Initialize
Hardware, WiFi, Display
2
Capture
Channel hopping, packet capture
3
Analyze
Parse, classify, detect anomalies
4
Output
Serial + Display updates

Hardware Design & Implementation

Design Process

The hardware design was developed using Autodesk Fusion 360, focusing on functional ergonomics, and following parametric 3d modeling design standards. parametric tolerance of 0.1mm were used accross all features of the design. thre is not a single screw visable to the end user, the base of the design followed a proffesinal standard of fillet-chammfer to allign with 3d printers limitations. the screen sits perfectly flush with the face of the body. The enclosure was 3D printed at a local maker zone.

Hardware Specifications

Component Specification Purpose
Microcontroller ESP32-WROVER Main processing unit with WiFi capabilities
Display 1.3" ST7789 (240x240) Visual interface for real-time data
Interface Touch sensors (GPIO 32/33) Navigation and interaction
Power Micro USB + Capacitor Stable power supply and filtering
Enclosure 3D Printed (PLA/PETG) Professional housing

Pin Configuration

// Display Configuration SPI_SCLK = GPIO 18 SPI_MOSI = GPIO 23 SPI_DC = GPIO 5 SPI_RST = GPIO 4 SPI_CS = -1 (Hardwired) // Touch Interface PIN_NEXT = GPIO 32 (Next card) PIN_SCROLL = GPIO 33 (Scroll within card) // Power Management VCC_OUT = GPIO 25 (3.3V output) GND_OUT = GPIO 26 (Ground reference)

Software Architecture

Core Libraries & Dependencies

#include <Arduino.h> // Core Arduino framework #include <WiFi.h> // ESP32 WiFi functionality #include <esp_wifi.h> // Low-level WiFi control #include <lvgl.h> // GUI framework #include <LovyanGFX.hpp> // Display driver #include <map> // STL containers #include <vector> // Dynamic arrays #include <set> // Unique element storage

Data Structures

APInfo Structure

Stores access point information including SSID, BSSID, channel, RSSI, security type, and associated clients.

ClientInfo Structure

Manages client device data with MAC address, vendor identification, connection status, and frame statistics.

AnomalyTracker Structure

Tracks suspicious behavior patterns including probe floods, deauth attacks, and channel hopping.

ChannelStats Structure

Maintains per-channel statistics for activity analysis and network mapping.

Key Algorithms

Packet Processing Algorithm

1
WiFi promiscuous mode captures all packets on current channel
2
Frame type classification (Management/Data/Control)
3
MAC address extraction and vendor identification
4
SSID parsing for beacon frames and probe requests
5
Security analysis and anomaly detection
6
Data structure updates and serial output generation

User Interface Design

Display Interface - LVGL Implementation

The main interface is designed for the serial console, providing comprehensive technical analysis. The display serves as a supplementary visual interface showing basic statistics and real-time network overview.

Access Points Card

Shows discovered APs with signal strength visualization

Channel: 1 | Security: WPA2 | Clients: 5

Devices Card

Lists client devices with vendor identification

Apple Device | -45dBm | Connected

Samsung Device | -52dBm | Scanning

Target Hunt Card

Real-time target device tracking

Status: FOUND | Signal: -45dBm

TX: 15 | RX: 8 | Last: 2s ago

Signal Map Card

Channel activity visualization

CH1 | CH2 | CH3 | Activity Levels

Network Intel Card

Security analysis and statistics

Secure Networks: 75%

Threats Card

Anomaly alerts and flagged devices

Active Threats: 2

Flagged MACs: 3

System Status Card

System information and uptime

Uptime: 02:15:30

Memory: 45% | Version: 2.0

Serial Interface - Primary Technical Interface

// Classic Packet Format (VERBOSE Mode) [CH1] [BEACON] [RSSI:-45] [SRC:AA:BB:CC:DD:EE:FF] [DST:FF:FF:FF:FF:FF:FF] [SSID:MyWiFi] [CH1] [PROBE_REQ] [RSSI:-52] [SRC:11:22:33:44:55:66] [DST:FF:FF:FF:FF:FF:FF] [SSID:TargetNetwork] // Professional Notifications (NORMAL Mode) [12:34:56] NEW_AP: "MyWiFi" (WPA2, CH1) [12:34:57] NEW_DEVICE: Apple device (Good signal, Client) [12:34:58] THREAT_DETECTED: PROBE_FLOOD from 11:22:33 (count: 15) // Live Dashboard (ANALYST Mode) ESP32 WiFi Intelligence System 12:34:56 | Uptime: 00:05:23 CH: 1/13 | Activity: 45/min Target: FOUND (-45dBm, 2s ago) | Devices: 12 APs: 8 | Threats: 2 | Security: 75%

System Workflow

Initialization Process

1
Hardware initialization (GPIO, RTC, power management)
2
Display initialization (ST7789, LVGL, UI creation)
3
WiFi initialization (promiscuous mode, channel setup)
4
Data structure initialization and memory allocation
5
Packet handler registration and system ready

Runtime Operation

1
Channel hopping every 3 seconds (1-13)
2
Packet capture and analysis in real-time
3
Anomaly detection and threat assessment
4
Serial output generation based on mode
5
Display updates every 2 seconds
6
Touch input processing and UI navigation

Advanced Features

Target Device Tracking

Monitor specific MAC addresses with TX/RX packet analysis, signal strength tracking, and behavioral pattern recognition.

Anomaly Detection

Advanced threat detection including probe floods, deauth attacks, beacon floods, and suspicious channel hopping patterns.

Vendor Identification

Automatic device classification based on MAC address OUI (Organizationally Unique Identifier) for Apple, Samsung, Raspberry Pi, and other vendors.

Security Analysis

Real-time identification of open networks, weak security configurations, and potential vulnerabilities in the network environment.

Network Mapping

Automatic AP-client association mapping based on signal strength, timing, and packet analysis for comprehensive network topology understanding.

Rate Limiting

Intelligent output management with configurable rate limiting to prevent serial buffer overflow and maintain system performance.

Output Modes

Mode Description Use Case
SILENT Only critical alerts Background monitoring
QUIET Anomalies + discoveries Security monitoring
NORMAL Intelligent summaries General use (default)
VERBOSE Rate-limited packets Detailed analysis
DEBUG Full technical details Development/debugging
ANALYST Professional dashboard Network intelligence

Usage Guide

Getting Started

1. Connect ESP32 via USB 2. Upload firmware using PlatformIO or Arduino IDE 3. Open serial monitor at 115200 baud 4. Configure target MAC address in code if needed 5. System will start automatically in NORMAL mode

Serial Commands Reference

Command Function Example
h Help menu Shows all available commands
s Device summary Lists all discovered devices
f Frame statistics Shows packet counts by type
t Target status Shows target device information
v VERBOSE mode Enables detailed packet output
z ANALYST mode Professional dashboard view
live Live dashboard Real-time system overview

Display Navigation

Touch Interface:
• GPIO 32 (Short press): Next card
• GPIO 32 (Long press): Refresh current card
• GPIO 33 (Short press): Scroll within card
• GPIO 33 (Long press): Reset scroll position

Professional Use Cases

Network Security Assessment

Identify unauthorized devices, detect rogue access points, and monitor for suspicious network activity patterns.

RF Environment Analysis

Analyze WiFi channel utilization, identify interference sources, and optimize network planning.

Device Tracking

Monitor specific devices for security purposes, track device movements, and analyze behavioral patterns.

Network Documentation

Generate comprehensive network maps, document device inventories, and create security reports.

Related Projects & Resources

Similar Projects

Technical Resources

  • IEEE 802.11 Standard - WiFi protocol specifications
  • ESP32 Technical Reference - Hardware documentation
  • LVGL Documentation - GUI framework guide
  • PlatformIO - Development platform documentation

Source Code

Complete source code and configuration files for the ESP32 WiFi Packet Sniffer project.

README.md

MARKDOWN
# ESP32 WiFi Packet Sniffer with Professional Display Interface

A sophisticated WiFi packet sniffer for the ESP32 Wrover Dev board with a 1.3" ST7789 display, featuring professional network intelligence capabilities.

##  Features

### Core Functionality
- **WiFi Packet Capture**: Captures management frames (beacons, probe requests/responses, association, authentication, etc.)
- **Channel Hopping**: Automatically switches between WiFi channels (1-13) every 3 seconds
- **Target Device Tracking**: Monitors specific MAC addresses with TX/RX packet analysis
- **Real-time Display**: Professional 240x240 ST7789 display interface with touch navigation

### Advanced Intelligence
- **Anomaly Detection**: Identifies probe floods, deauth attacks, beacon floods, and channel hopping
- **Device Classification**: Automatic vendor detection (Apple, Samsung, Raspberry Pi, etc.)
- **Security Analysis**: Identifies open networks and security vulnerabilities
- **Network Mapping**: Tracks AP-client associations and signal strength analysis

### Professional UI
- **7 Interactive Cards**: Access Points, Devices, Target Hunt, Signal Map, Network Intel, Threats, System Status
- **Animated Visualizations**: Signal strength bars, progress arcs, channel activity graphs
- **Touch Navigation**: PIN 32 (next card) and PIN 33 (scroll) for easy navigation
- **Real-time Updates**: Live statistics and professional color-coded information

### Serial Output Modes
- **SILENT**: Only critical alerts
- **QUIET**: Anomalies + new device discoveries
- **NORMAL**: Intelligent summaries (default)
- **VERBOSE**: Rate-limited packet samples with classic format
- **DEBUG**: Full technical details
- **ANALYST**: Professional network intelligence dashboard

##  Hardware Requirements

- **ESP32 Wrover Dev board** (or compatible ESP32)
- **1.3" ST7789 Display** (240x240 resolution)
- **Touch sensors** on GPIO 32 and 33 (optional)

### Pin Connections
- **Display**: SPI pins (18, 23, 5, 4)
- **Touch**: GPIO 32 (next card), GPIO 33 (scroll)
- **Power**: GPIO 25 (VCC), GPIO 26 (GND)


### 3. Serial Commands
- `h` - Help menu
- `s` - Device summary table
- `f` - Frame statistics
- `t` - Target phone status
- `r` - Reset counters
- `0` - SILENT mode
- `q` - QUIET mode
- `n` - NORMAL mode
- `v` - VERBOSE mode
- `x` - DEBUG mode
- `z` - ANALYST mode
- `live` - Show live dashboard
- `scan` - Manual intelligence report

##  Output Examples

### Classic Packet Format (VERBOSE Mode)
```
[CH1] [BEACON] [RSSI:-45] [SRC:AA:BB:CC:DD:EE:FF] [DST:FF:FF:FF:FF:FF:FF] [SSID:MyWiFi]
[CH1] [PROBE_REQ] [RSSI:-52] [SRC:11:22:33:44:55:66] [DST:FF:FF:FF:FF:FF:FF] [SSID:TargetNetwork]
```



##  Display Interface

The device features a professional touchscreen interface with:

- **Access Points Card**: Shows AP details with signal strength bars and security badges
- **Devices Card**: Lists client devices with vendor identification and connection status
- **Target Hunt Card**: Real-time target device tracking with signal visualization
- **Signal Map Card**: Channel activity graph showing network distribution
- **Network Intel Card**: Security analysis and frame statistics
- **Threats Card**: Anomaly alerts and flagged devices
- **System Status Card**: Uptime, memory usage, and system information

##  Target Device Tracking
Configure your target device MAC address in the code:
```cpp
const char* TARGET_PHONE = "C4:EF:3D:B3:23:BD";  // Your device's MAC
```

The system will:
- Track TX/RX packets from the target
- Monitor signal strength changes
- Detect network associations
- Provide real-time status updates


##  Project Structure

```
esp32-sniffer/
├── src/
│   ├── main.cpp          # Main application code
│   └── lv_conf.h         # LVGL configuration
├── include/              # Header files
├── lib/                  # Library files
├── platformio.ini        # PlatformIO configuration
├── cpp.cpp              # Simple WiFi sniffer (basic version)
├── cp.cpp               # Advanced version with enhanced features
└── README.md            # This file
```

## 🤝 Contributing

This project was developed as part of an IAESTE internship at Ege University. Contributions are welcome!

## 📄 License

This project is for educational purposes. Please use responsibly.

---

**Author:** Almoulla Al Maawali  
**Institution:** IAESTE Internship - Ege University  
**Project:** Professional WiFi Network Intelligence System